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ABSTRACT 

This  technical  report  contains  recommendations  for  guidelines  and  standards  to  be  used 
in  developing  Ada  programs  and  technical  documents  for  delivery  to  the  repository. 
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PREFACE 

This  document  conforms  to  Boeing  standards  and  guidelines 


Notice:  The  contents  of  this  document  is  available  in  electronic  form  on  the  S  I'ARS 
Repository  in  Wichita,  Kansas.  It  may  be  found  in  the  Boeing  directory  for  increment 
one  deliveries  under  Q  Task  12:  Guidelines  and  Repository. 
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1.  SCOPE 

1.1  Identification 

This  technical  report  makes  recommendations  for  guidelines  and  standards  to  be 
adopted  for  items  delivered  to  the  STARS  repository.  The  guidelines  and  standards 
cover  Ada  source  code,  including  specifications,  and  technical  documentation. 

1.2  Purpose 

The  STARS  repository  is  "to  facilitate  the  distribution  and  sharing  of  softw'are  and 
documentation  including  interim  and  final  results. ...Delivery  of  software  will  not  be 
considered  complete  until  code,  along  with  confirmation  of  its  compilation  by  the 
prime-contractor-designated  peer  review  using  a  validated  DoD  compiler,  has  been 
made  available  for  a  designated  STARS  repository."  Guidelines  and  standards  for 
software  and  documentation,  if  used,  simplify  the  sharing  of  textual  and  graphical 
material.  To  this  end,  the  repository  will  not  only  provide  guidelines  and  standards  but 
will  also  acquire  tools  that  assist  the  repository  users'  in  preparation  of  items 
according  to  these  standards  and  assist  the  repository  administration  in  enforcement  of 
these  standards. 

1.3  Introduction 

Guidelines  and  standards  not  only  impose  a  uniformity  on  the  format  of  material  but 
also  provide  standards  that  should  enliance  the  reusability  and  portability  of  code  and 
provide  standards  for  content  that  can  be  used  to  identify  delivered  items  for  later 
retrieval. 

Several  existing  standards  are  or  may  be  applicable  to  setting  up  and  enforcing 
guidelines  for  the  repository.  These  are:  (I)  Standardized  General  Markup  Language 
(SGML),  which  is  a  system  for  writing  grammars  that  describe  the  structure  of  text 
material,  (2)  Ada  Language  Specification,  (3)  IGES,  which  is  a  standard  for  simple 
graphics,  (4)  Information  Resource  Dictionary  System  (IRDS),  which  is  a  standard 
for  description  of  an  information  model  that  may  be  useful  for  interchange  of  designs 
that  are  hybrids  of  text  and  graphical  material,  (5)  Postscript,  which  is  a  standard  for 
page  description,  and  (6)  X  Windows,  which  is  an  evolving  standard  for  terminal  and 
workstation  display. 
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2.  REFERENCED  DOCUMENTS 

This  section  lists  pertinent  material  directly  and  in-directly  referenced  in  this 
document. 

[1]  STARS  Repository  Preliminary  System  Description,  1987. 

[2]  CDRL  00670,  "General  S/W  Development  Plan",  The  Boeing  Company. 
December  15,  1988. 

[3]  SPC-TR-87-105,  "Ada  Style  Guide",  Software  Productivity  Consortium. 
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3.  Guidelines  and  Standards  for  Ada  Source 

The  intention  for  source  code  delivered  to  the  repository  is  that  it  be  reusable  on  other 
projects  and  programs.  At  a  minimum,  to  be  reusable  the  source  code  must  compile 
correctly.  However,  compilation  does  not  guarantee  that  the  code  is  correct,  nor  that 
someone  else  can  understand  what  the  code  is  used  for  or  how  to  port  the  code  to 
different  compilation  systems  or  different  operating  systems.  Style  guides  provide 
recommendations  that  help  Ada  code  be  more  portable  and  reusable.  Standard 
prologues  can  be  used  to  gather  information  that  can  be  used  to  make  the  code  and 
context  in  which  the  code  is  to  be  used  more  understandable. 

3.1  Ada  Source  Code  Style  Guidelines 

The  recommendations  for  style  guidelines  to  be  followed  for  Ada  source  items  delivered 
to  the  repository  are  identical  to  those  found  in  the  Boeing  Sd'ARS  General  S/W 
Development  Plan,  CDRL  00670.  7’hese  guidelines  extend  those  given  in  the  Softw'are 
Productivity  Consortium's  (SPC)  Ada  Style  Guidelines.  The  SPC  Ada  Style 
Guidelines  are  available  on-line  at  the  repository  under  the  general  information 
directory.  The  Boeing  extensions  include: 

•  Ada  language  keyevords  shall  be  low'ercase. 

•  The  first  character  of  each  wemd  in  an  identifier  name  shall  be  capitalized;  all 
other  characters  shall  be  in  lowercase. 

•  A  singlf^  <:nace  shall  placed  heOtre  and  after  ear-h  delimiter. 

•  Three  spaces  shall  be  used  to  align  control  structures,  continuation  lines,  and 
embedded  units. 

•  A  single  blaiT,  line  shall  be  used  to  separate  logically  related  lines  of  text. 

•  The  maximum  line  length  shall  be  80  characters. 

•  Associate  identifiers  with  all  loops. 

•  Associate  identifiers  w'ith  all  nested  blocks. 

•  All  compilation  units  shall  contain  the  standard  prologue. 

•  Append  the  string  "_Type"  to  all  user  defined  types,  subtypes,  and  derived  types. 

Tools  that  fully  support  or  enforce  the  use  of  these  guidelines  do  not  yet  exist. 
Applicable  technology  includes  prettyprinters,  context-sensitive,  structure,  and  stream 
editors. 
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3.2  Ada  Design  Language  (ADL)  Guidelines 

The  recommendalions  for  style  and  format  guidelines  for  ADL  are  identical  to  those 
found  in  the  Boeing  STARS  General  S/W  Development  Plan,  CDRL  00670.  All 
ADL  statements  have  the  form  |  text',  which  allows  the  ADL  to  be  treated  by  an 
Ada  compiler  as  a  comment. 

There  are  standard  ADL  statements  bundled  together  as  a  prologue  (see  following 
section  for  definition)  to  provide  information  about  design  goals,  implementation 
details,  revision  history,  classification,  and  other  commentary  needed  to  facilitate 
reuse. 

3.3  Prologue  Guidelines 

The  standard  prologues  have  been  designed  to  capture  information  needed  for  reuse 
and  to  gather  inlormation  needed  lor  identifying  and  classifying  a  unit  for  the  catalog 
of  compilation  units  the  repository  must  support.  The  standard  prologues  are  both 
compilable  and  SGML-processable.  The  SG.ML  processable  requirement  allows  the 
use  of  the  full  power  of  SGML  to  validate  that  text  material  meets  a  defined  standard. 
Although  there  are  five  different  prologues  (the  Design  Header  and  Maintenance 
Header  for  non-nested  compilation  units,  the  Simple  Design  Header  and  Simple 
Subprogram  Header  for  nested  units,  and  the  STARS  Version  Description  for  a 
released  CSCI),  one  SGML  DTD  (Document  Type  Definition)  describes  them  all. 
.Given  the  DTD.  a  SGML  parser  that  completely  implements  the  SGML  standard  can 
validate  that  an  input  Ada  compilation  unit  meets  the  requirements  defined  in  that 
DTD.  Once  the  input  .Ada  compilation  unit  has  been  valiaaied,  the  SGML-tagged 
information  can  easily  be  loaded  into  some  database  that  is  cataloging  the  compilation 
uiu'ts  stored  on  the  repository. 

3.3.1  Design  Header 

This  prologue  is  to  be  used  for  the  lollowiiig  iU/ii-  nested  units;  standal'^^e  ‘^nbproizrams 
(compilation  units)  or  main  programs,  package  specifications  (that  have  bodies),  and 
generic  instantiations. 


This  is  a  model  of  the  prologue  "Design  Header" 
which  is  to  be  used  in  accordance  with  the 
Boeing  STARS  General  S/W  Development  Plan, 

CDRL  00670. 


—  Square  brackets  enclose  optional  items. 

—  Braces  enclose  items  which  may  be  repeated 

—  zero  or  more  times. 
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[ 


—  I  Descript ive_Unit_Najme> 
text  ] 


— i Descriptioni 
—  I  {text) 

— i i Descriptioni 


—  1  Reguireinents_Satisf  ied> 

—  I  (text) 

—  I  I Requirements_Satisf ied> 


I  Revision_History > 

I  Part_Number >  text 

{Author)  text 

I  [ — iPhone)  text] 

j  [ — IddN)  text] 

I  Version)  text 

I  Change_Suminary_Initial_Release) 
iDate)  text 


(subsequent  changes 
Author)  text 

[--jptione)  text] 

( — |ddN)  text] 

Version)  text 

Document s_associ at ed_with_revis ion) 
Change_Suminary )  text 
Date)  text 

Release_Date)  text  ) 

I Revision_History) 


text 


[ 


—  I Exceptions_Raised) 

{text ) 

—  I  1 Exceptions_Raised)  ] 


Implementation_Dependencies_NONE) 

—  use  following  if  dependencies  are  located  in  the  package  body. 
Warning_Contains_Dependencies) 

—  use  following  if  dependencies  are  located  in  the  package  spec. 
Warning_Unit_Contains_Iniplementation_Dependencies ) 

Pragma_Usage) 

{text ) 

Represent a tion_Clause_Usage) 

{ text ) 

Hardware_Dependencies) 
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— i  {text) 

—  I Compiler_Dependencies  > 

—  I  {text) 

--  1  I  Warning_Unit_Contains_Iir.plementation_Dependencie£> 

—  I  Iinplen!entation_As£uitiption£_KO’-.'E> 

-- I  —  use  folloving  if  implementation  assumptions  are  located  in 
— j  —  the  package  body. 

--  \  Warning_ContainE_Implementation_.As£umpt  ions  > 

—  I  —  use  following  if  located  in  package  specification. 

—  j  Warning_Unit_Contains_Implementation_As£uinptions> 

--  !  Use_  .^issumptions  > 

--|  (text) 

— i Per formance_Assumptions > 

—  I  (text) 

—  I  I Warning_Unit_Contains_Implementation_A£sumptions> 

-- 1 Distribution_and_Copyright> 

-- I  This  prologue  must  be  included  in  all  copies  of  this  software. 

—  I  This  software  is  released  to  the  Ada  community. 

—  I  This  software  is  released  to  the  Public  Domain  (note: 

-- I  software  released  to  the  Public  Domain  is  not  subject  to 

—  ■  copyright  protection). 

-- I  Restrictions  on  use  or  distribution;  NONE 

-I 

—  j  Disclaimer  > 

-- I  This  software  and  its  documentation  are  provided  "AS  IS'  and 
-- I  without  any  expressed  or  implied  warranties  w'hatsoever. 

--|  No  warranties  as  to  performance,  merchantability,  or  fitness 
--|  for  a  particular  purpose  exist. 

-I 

—  I  Because  of  the  diversity  of  conditions  and  hardware  under 
-- I  which  this  software  may  be  used,  no  warranty  of  fitness  for 

—  I  a  particular  purpose  is  offered.  Ti.e  user  is  advised  to  test 

—  I  the  software  thoroughly  before  relying  on  it.  The  user 
-- I  must  assumie  the  entire  risk  and  liability  of  using  this 

—  I  software. 

-i 

-- I  In  no  event  shall  any  person  or  organisation  of  people  be 
-- I  held  responsible  for  any  direct,  indirect,  consequential 
-- I  or  inconsequential  damages  or  lost  of  profits. 

—  i  ] Disclaimer  > 
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3.3.2  Maintenance  Header 

This  prologue  is  to  be  used  for  the  following  ncn-nested  units:  package  specifications 
(that  do  not  have  bodies),  subprogram  bodies,  package  bodies,  and  task  bodies. 


—  -  This  is  a  model  of  the  prologue  "Maintenance 

—  Header"  which  is  to  be  used  in  accordance 

—  with  the  Boeing  STARS  General  S/W 

—  Development  Plan,  C^RL  00670. 

—  Square  brackets  enclose  optional  items. 

—  Braces  enclose  items  which  may  be  repeated 

—  zero  or  more  times. 

—  Note:  packages  without  bodies  use  this 

—  prologue. 


[  — I Descriptive_Unit_Name> 
text  ] 

Description> 

{text ) 

I  Descr:.ption> 

Requirements_Satisf ied> 

{ text ) 

1 Requirements_Satisf ied> 


—  1  Rev: sion_History > 

—  I Part_Number >  text 

—  1  Author >  text 

—  I  [ — |phone>  text] 

— i  [ — |DDN>  text] 

— iversion>  text 

—  I Change_Summary_Initial_Release> 

—  I  Date>  text 


—  I  [subsequent  changes 

— i Author >  text 

—  I  [ — |Phone>  text] 

—  I  [— |DDN>  text] 

— |version>  text 

-- I  Documents  associated  with  revision>  text 
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—  I  Change_Suinmary>  text 

—  I  Date >  text 

—  I Release_Date>  text  } 

—  I  I Revision_Kistory> 

—  I  [  — I  Except!  )ns_Raised> 

—  I  {text) 

—  I  — I  I Exceptions_Raised>  ] 

—  1 Implementation_Dependencies_NONE> 

—  I  —  use  following  if  dependencies  are  located  in  the  package  body. 

—  I  Warning_Contains_Dependencies  > 

—  I  —  use  following  if  dependencies  are  located  in  the  package  spec. 

—  I  Warning_Unit_Contains_Impleinentation_Dependencies  > 

—  I Pragma_Usage> 

—  1  {text) 

—  I Representation_Clause_Usage> 

—  I  {text) 

—  I Hardware_Dependencies> 

—  I  {text) 

—  I  Coinpiler_Dependencies> 

—  I  {text) 

—  1  I  V!arning_'Unit_Contains_Impleinentation_Dependencies> 

—  I  Iinpleinentation_Assuittptions_NONE> 

—  I  —  use  following  if  implementation  assumptions  are  located  in 

—  I  —  the  package  body. 

—  1 Warning_Contains_Iraplementation_Assumptions> 

—  I  —  use  following  if  located  in  package  specification. 

—  1  Warning_Unit_Contains_Implementation_Assvunptions  > 

—  I Use_Assumptions  > 

—  I  {text) 

—  I Performance_Assumptions> 

—  1  {text) 

—  I  I Warning_Unit_Contains_Implementation_Assumptions> 

—  1 Lessons_Learned> 

—  I  {text) 

—  I  I Lessons_Learned> 

—  I Contact> 

--|  {text) 

—  I ! Contact) 


—  I Distribution_and_Copyright> 
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This  prologue  must  be  included  in  all  copies  of  this  software. 
This  software  is  released  to  the  Ada  community. 

This  software  is  released  to  the  Public  Domain  (note: 
software  released  to  the  Public  Domain  is  not  subject  to 
copyright  protection) . 

Restrictions  on  use  or  distribution;  NONE 


—  I  Disclaimer > 

—  I  This  software  and  its  documentation  are  provided  "AS  IS"  and 

—  I  without  any  expressed  or  implied  warranties  whatsoever. 

—  I  No  warranties  as  to  performance,  merchantability,  or  fitness 

—  I  for  a  particular  purpose  exist. 

—  I  Because  of  the  diversity  of  conditions  and  hardware  under 

—  I  which  this  software  may  be  used,  no  warranty  of  fitness  for 

—  I  a  particular  purpose  is  offered.  The  user  is  advised  to  test 

—  I  the  software  thoroughly  before  relying  on  it .  The  user 

—  1  must  assume  the  entire  risk  and  liability  of  using  this 

—  I  software. 

—  I  In  no  event  shall  any  person  or  organization  of  people  be 

—  I  held  responsible  for  any  direct,  indirect,  consequential 

—  I  or  inconsequential  dcimages  or  lost  of  profits. 

—  1  1  Disclaimer > 


3.3.3  Simple  Design  Header 

This  prologue  is  to  be  used  for  the  following  nested  units:  package  specifications,  task 
specifications,  generic  (package)  instantiations,  package  bodies,  and  task  bodies. 


—  I  —  This  is  a  model  of  the  prologue  "Simple 

—  I  —  Design  Header"  which  is  to  be  used  in 

—  j-  —  accordance  with  the  Boeing  STARS  General 

—  I  —  S/W  Development  Plan,  CDRL  00670. 

—  I  —  Square  brackets  enclose  optional  items. 

-- 1  —  Braces  enclose  items  which  may  be  repeated 
— [  —  zero  or  more  times. 


—  !  [  — 1 Description> 

—  I  (text) 

—  I  — i  I Description>  ] 
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—  I  [  — I Exceptions_Raised> 

—  I  {text) 

—  I  — I  I Exceptions_Raised>  ] 

3.3.4  Simple  Subprogram  Header 

This  prologue  is  to  be  used  for  the  following  nested  units:  subprogram  specifications, 
generic  (subprogram)  instantiations,  and  subprogram  bodies. 


—  I  —  This  is  a  model  of  the  prologue  "Simple 

—  I  —  Subprogram  Header"  which  is  to  be  used  in 

—  I  —  accordance  with  the  Boeing  STARS  General 

—  I  —  S/W  Development  Plan,  CDRL  00670. 

—  I  —  Scfuare  brackets  enclose  optional  items. 

—  I  —  Braces  enclose  items  which  may  be  repeated 

—  I  —  zero  or  more  times. 


—  I  [  — I Description> 

—  I  {text) 

—  1  — 1 1 Description>  ] 

—  I  [  — I Exceptions_Raised> 

—  I  {text) 

—  I  — I  I Exceptions_Raised>  ] 

3.3.5  STARS  Version  Description 

This  prologue  is  to  be  used  for  the  Version  Description  Package  which  accompanies 
each  CSCI  release. 


This  is  a  model  of  the  "STARS  Version 
Description"  which  is  to  be  used  in 
accordance  with  the  Boeing  STARS  General 
S/W  Development  Plan,  CDRL  00670. 

Square  brackets  enclose  optional  items. 
Braces  enclose  items  which  may  be  repeated 
zero  or  more  times. 


—  I Revision_History> 
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Part_Number>  text 

Author >  text 

[ — 1  Phone >  text] 

[ — |dDN>  text] 

Version)  text 

Change_Suinmary_Initial_Release> 
Date)  text 


{subsequent  chan^w^ 

Author)  text 

[ — I  Phone)  text] 

[ — |ddn)  text] 

Version)  text 

Document s_associated_with_revision)  text 
Change_Suinmary)  text 
Date)  text 

Release_Date)  text  ] 

I Revision_History) 


—  I Class_I_Changes_Installed) 

—  I  List  the  new  Class  I  changes  to  the  CSCl/tool  since  the  previous 

—  I  version/change.  Also  identify  for  each  entry  in  this  list' the 

—  I  related  documentation  (e.g.,  SPR)  number  and  date. 

—  I  This  information  does  not  apply  to  an  initial  release. 

—  I  1 Class_l_Changes_lnstalled) 


—  I Class_II_Changes_Installed> 

—  I  List  the  new  Class  II  changes  to  the  CSCI/tool  since  the  previous 

—  I  version/change.  Also  identify  for  each  entry  in  this  list  the 

—  I  related  documentation  (e.g.,  SPR)  number  and  date. 

—  I  This  information  does  not  apply  to  an  initial  release. 

—  I  I Class_II_Changes_Installed) 


CSCI_Architecture) 

Identify  and  describe  the  static  architecture  of  the  CSCI/tool. 
or  Buhr  diagreuns  may  be  referenced. 

(STLDD  3.1) 


Booch 


Identify  each  compilation  unit  delivered  with  the  CSCI/tool.  Exeunple 
Nesting  will  identify  each  TLCSC,  etc.  begining  with  the  TLCSC  name 
followed  by  each  of  the  names  of  the  Ada  compilation  units  that  it 
withs  (in  compilation  order).  The  CSCI  must  be  identified  by  a  part 
number.  In  addition  any  standalone  TLCSC  must  also  be  identified  by 
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a  part  number.  A  standalone  TLCSC  is  a  driver  that  performs  the 
function  of  a  tool  that  is  not  nested  in  the  main  program  of  a  CSCI . 
The  part  nuber  is  associated  with  the  file  containing  the  main  program 
or  top  level  package . 

I  CSCI  Architecture > 


—  I Virtual_Interfaces> 

—  I  Identify  the  virtual  interface(s)  used  by  this  CSCI/tool. 

—  I  (e.g.,  X  Windows,  GKS,  CAIS,  SQL). 

—  I  (SRS  3.3.1,  3.3.2) 

—  I  (SDDD  3.1,  3.1.x,  3.1.X.1,  3. 1.x. 2,  3. 1.x. 3) 

—  I  I Virtual_Interfaces> 


—  I Tool_Interfaces> 

—  I  Identify  the  tool  interface(s)  to  this  CSCI/tool. 

—  I  (SRS  3.3.3.1.X) 

—  I  (SDDD  3.1,  3.1.x,  3.1.X.1,  3. 1.x. 2,  3. 1.x. 3) 

—  I  I Tool_Interfaces> 


—  I Hardware_Interfaces> 

—  I  Identify  the  hardware  interface(s)  to  this  CSCI/tool. 
--I  (SRS  3.3.3.2.Y) 

—  1  (SDDD  3.1,  3.1.x,  3.1.X.1,  3. 1.x. 2,  3. 1.x. 3)  . 

—  I  I Hardware_Interfaces> 


—  I Functional_Control_and_Data_Flow> 

—  I  Describe  the  general  high  level  flow  of  both  control  and  data. 

—  I  A  narative  must  be  used  to  document  the  flow  of  data  and  control. 

—  1  The  following  diagraming  techniques  may  be  referenced;  A  control  flow 

—  I  diagram  may  be  used  to  represent  control  flow.  A  data  flow  diagram 

—  I  may  be  used  to  describe  the  data  flow.  If  the  tool  is  concurrent, 

—  I  then  provide  a  finite  state  model  diagram.  Buhr  diagrams  may  be  used 

—  1  to  display  control  and  data  flow. 

—  I  ( STLDD  3.4) 

—  I  I Functional_Control_and_Data_Flow> 


System_Environment> 

Describe  the  environmental  conditions  under  which  this  tool  will 
operate.  (e.g.,  operating  system  and  revision  level,  dependence  on 
other  languages,  such  as,  FORTRAN,  C,  or  Assembly  routines  or  lib¬ 
raries  . 


(SRS  3.5.1) 

This  software  was  developed  on  the  following  hardware  platform, 
operating  system,  Ada  compilation  system,  (C  compiler,  and  virtual 
interfaces,  including;  MIL-STD-1838  CAIS  and  X  Windows  Version  11R2. 
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Gould  General  Systems  Division  -  NPl  Packaged  System  (SPU,  128  MB) 
Part  No.  40518-021. 

Gould  UTX/32  Operating  System  Rel .  3.1  (UNIX  Berkeley  4.3  kernel 
with  System  V  extensions).  Part  No.  1470-0803. 

Gould  RPLEX  Ada  Compiler  BSS  (NP-1).  Part  No.  81040-2803. 

Gould  C  Compiler  with  MCR  Optimizer  (NPL).  Part  No.  1707-0803. 

Gould  CAIS  MIL-STD-.1838  Prototype,  Part  No.  0006 
I  System_Environment> 


—  I System_Parameters> 

—  I  Describe  the  parameters  or  constants  that  are  used  by  the  CSCI . 

—  I  Identify  package  specifications  which  document  these  constraints. 

—  I  (SRS  3.5.2) 

—  I  I System_Parameters> 


—  I System_Capacities> 

—  I  Describe  and  document  the  storage  and  execution  requirements  of  the 

—  I  tool  (e.g.,  memory  and  disk  requirements).  Identify 

—  I  compilation  units  which  are  affected  by  these  limitations. 

—  I  (SRS  3.5.3) 

—  I  I System_Capacities> 


—  I Installation_Instructions> 

—  I  Include  an  install  file  identifying  the  computer  system  and  Ada 

— i  compiler  version  that  this  batch  install  file  was  compiled  on.  This 

—  1  will  allow  a  user  to  cut  this  section  out,  delete  the  comment  tokens 

—  I  and  execute  this  batch  command  file  to  compile  all  of  the  sources 

—  I  required  for  the  tool . 

—  I  (VDD  3.9) 

—  1  I Installation_lnstructions> 


—  I Inventory_of_CSCI_Contents> 

—  I  Provide  a  cross  reference  of  compilation  units  and  their  associated 

—  I  files  by  creating  a  list  each  of  the  ada  compilation  units  in 

—  I  alphabetical  order  followed  by  the  name  of  the  file  that  contains 

—  I  the  compilation  unit.  (e  g..  Some  reusable  software  has  more  than 

—  I  one  specification,  etc.  per  file.  (e.g.,  package  example  ■  filename) 

—  I  I Inventory_of_CSCI_Contents> 


Adaptation_Data  > 

Identify  and  describe  the  data  ■which  is  required  during  tool 
initialization.  These  data  should  resemble  the  system  environment 
and  parameter  information.  Also,  identify  the  package  specifications 
which  implement  these  data. 
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•|  (STLDD  3.7) 

I  I Adaptation_Data> 


Lessons_Learned> 

Enter  lessons  learned  from  the  development  of  this  tool . 

1.  Verdix  compiler  does  not  recognize  file  names  with  greater  than  24 
characters . 

1 Lessons_Learnfed> 

Classif ication_Facets> 

Voice> 

Indicate  the  relation  between  the  component  and  the  operating 
environment . 

Operating_System> 

Indicate  the  possible  operating  system  in  which  the  component  can  be 
invoked . 

Lowest_Operating_System_Version> 

Indicate  the  lowest  version  level  of  operating  system  on  which  the 
component  can  be  used, 

Highest_Operating_System_Version> 

Indicate  the  highest  version  level  of  operating  system  on  ■which  the 
component  can  be  used. 

Compilation_System> 

List  the  compilation  system(s)  in  which  the  component  has  correctly 
compiled . 

Lowest_Compilation_System_'Version> 

Indicate  the  lowest  version  level  of  operating  system  on  which  the 
component  has  been  successfully  compiled. 

Highest_Compilation_System_Version> 

Indicate  the  highest  version  level  of  operating  system  on  which  the 
component  has  been  successfully  compiled. 

Function> 

Describe  the  function  of  the  component  or  of  the  component  in  which 
the  component  could  be  used. 

External_Interf ace> 

Describe  the  form  of  external  interface(s) . 
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Application_Area> 

Describe  the  possible  application  area(s). 

Entity> 

List  the  entities  manipulated  by  the  component. 

Action> 

Describe  the  action  performed  on  the  entities. 

Medium> 

Give  the  locale  where  the  action  is  executed. 

Domain > 

Describe  the  business,  engineering,  mathematical,  scientific  domain(s) 
in  which  the  component  can  apply. 

I Classif ication_Facets> 

Distribution_and_Copyright> 

This  prologue  must  be  included  in  all  copies  of  this  software. 

This  software  is  released  to  the  Ada  community. 

This  software  is  released  to  the  Public  Domain  (Note: 
software  released  to  the  Public  Domain  is  not  subject 
to  copyright  protection) . 

Restrictions  on  use  or  distribution:  NONE 


—  I  Disclaimer > 

—  I  This  software  and  its  documentation  are  provided  "AS  IS"  and 

—  I  without  any  expressed  or  implied  warranties  whatsoever. 

—  I  No  warranties  as  to  performance,  merchantability,  or  fitness 

—  I  for  a  particular  purpose  exist. 

—  I  Because  of  the  diversity  of  conditions  and  hardware  under 

—  I  which  this  software  may  be  used,  no  warranty  of  fitness  for 

—  I  a  particular  purpose  is  offered.  The  user  is  advised  to  test 

—  I  the  software  thoroughly  before  relying  on  it .  The  user 

—  I  must  assume  the  entire  risk  and  liability  of  using  this 

—  I  software. 

—  I  In  no  event  shall  any  person  or  organization  of  people  be 

—  I  held  responsible  for  any  direct,  indirect,  consequential 

—  I  or  inconsecjuential  damages  or  lost  profits. 

—  I  I  Disclaimer > 


$ 
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3.3.6  SGML  DTD  for  Prologues 

TTie  current  version  of  the  SGML  DTD  that  would  validate  a  prologue  is: 


< ! DOCTYPE  adacode  [ 

<> —  The  ADL  (BNF)  in  the  STARS  Software  Development  Plan  was 
used  as  the  baseline.  Deviations  are  commented  — > 

<! ENTITY  %assumptions_annotation 
'  ( inipleinentation_assumptions_none  | 
warni.ng_contains_implementation_a£sumptions  | 

%assumptions_v?arning_annotation ; ) " > 

< ! ENTITY  %assumptions_warning_annotation 
■ (warning_unit_contains_implementation_assiimptions ) " > 

<! —  Design_Declarative_Part  ;;==  {design_basic_declarative_item) 

{de£ign_later_declarative_item} 
Design_Later_Declarative_Item  :;==  (design_body  | 

design_basic_subprogram_declaration  j 
de£ign_basic_package_declaration  | 
design_basic_ta ^k_declaration  | 
design_basic_generic_declaration  | 
design_basic_generic_instantiation  | 

# PCDATA) 

Design_Body  : : ==  (basic  proper  body  |  #PCDATA)  — > 

<!  ENTITY  %body_stuff  "((#PCDATA  |  basic_£ubprograiii_body  | 

basic_package_body  |  basic_task_body  | 
design_basic_subprogram_declaration  | 
design_basic_package_declaration  | 
%design_basic_task_declaration;  | 
design_basic_generic_declaration  | 
design_basic_generic_instantiation ) * ) " > 

<!E3^TITY  %contact_annotation  " (contact) '> 

< 'FNTTTY  %copyrlght_disclaimer  ' ( %copyright_disclaimer_annotation; )"> 

< ! ENTITY  %copyright_disclaimer_annotation 
■ (distribution_and_copyright ,  disclaimer) "> 
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<! ENTITY  %dependency_annotation 

■  ( iinpleinentation_dependencies_none  |  warning_contains_dependencies  | 
%dependency_varning_annotation; ) " > 

< ! ENTITY  %dependency_warning_annotation 

■  (warning_ur.it_contains_impleinentation_dependencies )  "> 

<! ENTITY  %description_annotation  " (description) " > 

<!ENTITY  %design_basic_task_declaration  " (design_simple_task_declaration  i 
design_rendezvous_ta£k_declaration ) ' > 

<!ENTITY  %design_header  ' ( %unit_ncLme_annotation; ?,  %requircd_part; , 
revi£ion_history ,  %optional_part; ?,  %impleinentation_annotation; , 
%copyright_disclaimer ; ) "> 

<!ENTITY  %design_package_header  * ( %unit_naine_annotation ; ? ,  %required_part; , 
revision_history,  %optional_part ,  %implementation_annotation; , 
%lessons_learned_annotation;  ?,  %contact_annotation;  ? ,  %copyright_disclaiiner  ,•  )"> 

<!  ENTITY  %de£ign_proper_body  “  (design_subprograiti_body  | 
design_package_body  |  design_task_body) " > 

<!E3\”ITY  %exceptions_annotation  ' (exceptions_raised) " > 

<  !  ENTITY  %iinplementation_annotation 

■  ( %dependency_annotation,' ,  %assuinptions_annotation; )  ”> 

< ! ENTITY  %initial_relea£e_annotation 

"(author,  phone^,  ddn?,  version,  change_sximinary_initial_release ,  date)"> 

<! ENTITY  %le£3ons_learned_annotation  " (lessons_learned) ' > 

< 'ENTITY  %inaintenance_header  '  (%unit_ncLme_annotation;  ?,  %reguired_part; , 
revision_history ,  %optional_part ;  ?,  %iinpleinentation_annotation; , 
%lessons_learned_annotation;  ,  %contact_annotation; ,  %copyright_disclaimer )  "> 

< '.ENTITY  %optional_part  '  (  %exceptions_annotation;  )  "  > 

<!  ENTITY  %required_part  "  ( %description_annotation; ,  %requireinents_annotation,' ) "  > 
<!ETJTITY  %requireinents_annotation  "  ( reguirejnents_satisf  ied) "  > 

<!ENTITY  %  simple_design_header  "  ( %description_annotation,- ? ,  %optional_part ;  ? ) "  > 
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<  !  ENTITY  %simple_subprogram_header  "  ( %description_annotation ? , 

%optional_part ,-  ? ) "  > 

<! —  Design_Basic_Declarative_Item  :;==  (design_basic_declaration  |  ^PCDATA)  — > 
<! ENTITY  %specification_stuff  ‘((^PCDATA  | 

design_basic_subprograin_declaration  | 
design_basic_package_declaration  | 
%design_basic_task_declaration ;  | 

design_basic_generic_declaration  | 
dGsign_basic_generic_inEtantiation ) * ) ' > 

< ! ENTITY  %subsequent_change_annotation 

"(author,  phone?,  ddn?,  version,  docuinents_associated_with_rev'ision, 
changG_suinmarY,  date,  release_date )  '  > 

<! ENTITY  %unit_naine_annotation  " ( descriptive_unit_name ) ' > 

<!—  ELEI-IENTS  NIN  CONTENT  (EXCEPTIONS)  —  > 

<!--  Design_Cotipilation_Unit  :;==  design_library_unit  | 

design_secondary_unit  | 
STARS_version_description 
Design_Secondary_L'nit  ;  :  ==  de£ign_library_unit_body  | 

de£ign_subunit  — > 

<  !  ELE.*-1ENT  adacode  -  -  (  ( (iPCDATA)  * ,  (design_subprograin_specif  ication  ! 

de£ign_package_£peci f icat :.on  | 
design_generic_specif icat ion  | 
design_generic_instantiation  | 
design_subprograiTi_body  | 
design_package_body  | 
design_subunit )  i 
STARS_ver£ion_description )  > 


<  'ELEMENT  design_subprograin_specif ication 

-  0  (#PCDATA,  %design_header ; ) > 

<1 —  Design_Package_Specif ication  ::==  (#PCDATA,  de£ign_package_header , 

{design_basic_dGclarative_itein) , 

[# PCDATA, 

{design_basic_declarative_itein]  ]  , 

# PCDATA) 

Design_Package_Header  :;==  (design_headGr  |  inaintenance_header )  — > 

<  !  ELEI'-'JENT  design_package_specif  ication 

-  0  (SPCDATA,  %design_package_header ; , 

%£pecif  ication_stuf  f ,- )  > 
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< ! ELEMENT  design_genGric_specif ication 

-  0  (#PCDATA,  (de£ign_subprograjn_specif ication  | 

design_package_specification) ) > 

<  .'ELEMENT  design_generic_instantiation 

-  0  (^PCDATA,  %design_header ,- )  > 

<! —  Design_Subprograin_Body  :  :  ==  (maintenance_subprograin_£pecification, 

[de£ign_declarative_part] ,  #PCDATA)  — > 

<  IELEKEIn-'T  de£ign_£ubprograiti_body 

-  0  (i;PCDATA,  %maintenance_header;  , 

%body_stuf f ,  ) > 

<1 —  Design_Package_Body  ::==  (fPCDATA,  inaintenance_header , 

[de£ign_declarative_part] ,  #PCDATA)  — > 

<  !  ELEI-IENT  de£ign_package_body 

-  0  (SPCDATA,  %maintenance_header; , 

%body_stuf  f ; ) > 

<  !  ELEJ'^ENT  de£ign_£ubunit 

-  0  (JiPCDATA,  %de£ign_proper_body ;  )  > 

<  '  ELEME!n’T  STARS_ver£ion_de£cription 

-  0  (fcPCDATA,  revi£ion_hi£tory , 

cla££_I_changes_in£talled, 
cla£s_II_change£_in£talled , 

CSCI_archit ecture ,  virtual_int erf  aces, 
tool_interf aces ,  hardvare_interf aces , 
f unct ional_control_and_data_f low, 
system_environinent ,  systein_parajneter  s , 
£y£tem_capacit  ies,  install  at  ion_ir,st  ructions  , 

1 nventory_of _CSCI_contents , 
adapt at ion_dat  a ,  lessons_lear ned , 
classif  ication_£acet£,  %copyrjght_disclaiiner,-  , 
# PCDATA ) > 

<!--  De£ign_Task_Body  : ; ==  (#PCDATA,  inaintendnce_header, 

[design_declarative_part]  ,  FPCDATA',  — > 

<!ELE?CENT  desi gn_ta£k_body 

-  0  (#PCDATA,  %inaintenanre  header;, 

%body_stuf  f ; ) > 

<  '  ELEl-lENT  class_I_changes_installed 

-  -  (»! PCDATA)  *> 

< ' ELEMENT  cla£S_I I_changes_in£tall ed 
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-  -  <  #  PCDATA ) *  > 

<  '  ELEI»IEIICT  CSCI_architecture 

-  -  (iiPCDATA)*> 

< ! ELEMENT  virtual_inter faces 

-  -  (#PCDATA)»> 


< ' ELEMENT  tool_interfaces 

-  -  (#PCDATA)*> 

< ! ELEMENT  hardware_inter faces 

-  -  (#PCDATA)*> 

< ! ELEMENT  f unctional_control_and_data_f low 

-  -  (#PCDATA)*> 

<  !  ELEMENT  system_envirorLnient 

-  ~  (I;  PCDATA )  *  > 

<  !  ELEMENT  system_paraineters 

-  -  (iiPCDATA)*> 

<! ELEMENT  system_capacities 

-  -  (*iPCDATA)*> 


<! ELEMENT  installation_instructions 

-  -  (# PCDATA) *> 

< 'ELEMENT  inventory_of_CSCI_contents 

-  -  (#PCDATA)*> 

< ' ELEMENT  adaptation_data 

-  -  (#PCDATA)*> 

<! ELEMENT  classif ication_f acets 

-  -  (voice,  operating_systein, 

lowest_operating_system_version , 
highestoperating_system_version , 
coinpilation_Eystein, 
lowest_compilat  ion_systein_version , 
highest_compilation_systein_version , 
function,  external_interf ace , 
application_area,  entity,  action, 
medium,  domain) > 
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<f ELEMENT  voice  -  0  (#PCDATA)> 

<  !  ELEMENT  operating_systeni 

-  0  (#PCDATA)> 

< ! ELEMENT  lowest_operating_systein_version 

-  0  (#PCDATA)> 

<  !  ELEI'-IENT  highest_operating_systein_version 

-  0  (#PCDATA)> 

<!  ELEMENT  coinpilation_systera 

-  0  (#PCDATA)> 

<  !  ELEl'iENT  lowest_compilation_systein_version 

-  0  (# PCDATA )> 

<  !  ELEIMENT  highest_coinpilation_systein_version 

-  0  (#PCDATA)> 

<! ELEMENT  function  -  0  (#PCDATA)> 

<! ELEMENT  external_interf ace 

-  0  (#PCDATA)> 

<! ELEMENT  application_area 

-  0  (#PCDATA)> 

<! ELEMENT  entity  -  0  (#PCDATA)> 

<!ELEI'IENT  action  -  0  (#PCDATA)> 

<! ELEMENT  medium  -  0  (#PCDATA)> 

<  !  ELEI'^iEl'IT  domain  -  0  (#PCDATA)> 

<!--  ELEMENTS  MIN  CONTENT  (EXCEPTIONS)  — > 

< ! ELEIIENT  de£ign_basic_subprograra_declaration 

-  0  (#PCDATA,  %simple_subprogram_header ; ) > 

<! —  De£ign_Basic_Package_Declaration  ::==  (SPCDATA, 

simple_design_header , 
(design_baEic_declarative_item) , 
[# PCDATA, 
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{design_basic_declarative_itein)  ]  , 
« PCDATA)  — > 

< ! ELEMENT  design_basic_package_declaration 

-  0  (#PCDATA,  %Eimple_design_header ; ) > 

< ! ELEMENT  design_simple_task_declaration 

-  0  (SPCDATA,  %Eiinple_design_header ;  )  > 

<! —  Design_Rendezvous_Task_Declaration  : : ==  (#PCDATA,  siinplG_de£ign_header , 

#PCDATA)  — > 

< ! ELEMENT  design_rende2vous_task_declaration 

-  0  (#PCDATA,  %simple_design_header; ) > 


<  ELEMENT  deEign_basic_generic_declaration 

-  0  (ifPCDATA,  (design_basic_subprograro_declaration  | 

design_ba£ic_package_declaration) ) > 

< ! ELEMENT  design_basic_generic_instantiation 

-  0  (#PCDATA,  (%siinple_design_header;  | 

%simple_subprogram_hGader  ,• ) )  > 

<! —  Basic_Subprogram_Body  : :==  (design_ba£ic_subprograjn_specification, 

(design_declarativG_part] ,  #PCDATA)  — > 

<!  ELEMENT  basic_subprograin_body 

-  0  (#PCDATA,  %siinple_subprograin_headGr;  )  > 

<! —  Basic_Package_Body  ; ;==  (#PCDATA,  siniple_design_header , 

[de£ign_declarative__part]  ,  ((PCDATA)  — > 

< ! ELEMENT  basic_packagG_body 

-  0  ((fPCDATA,  %siinplG_design_header ;  )  > 

<! —  Basic_Task_Body  : : ==  (SPCDATA,  siinplG_design_header , 

[design_declarative_part]  ,  (iPCDATA)  — > 

<! ELEMENT  baEic_task_body 

-  0  (#PCDATA,  %siinple_deEign_header ; )  > 

<! —  ELEMENTS  MIN  CONTENT  (EXCEPTIONS)  — > 

<  !  ELEMET'IT  descriptive_unit_nciine 

-  0  ((I PCDATA )> 

< ! ELEMENT  revision_history 

-  -  ( part_number ,  %initial_releasG_annotation; , 

%subseguent_change_annotation; * ) > 
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<!ELEI>ffiNT  contact  -  -  (#PCDATA)*> 

<! ELEMENT  lessons_learned 

-  -  (#PCDATA)*> 

< [ELEMENT  impleinentation_dependencies_none 

-  0  (4(PCDATA)»> 

< [ELEMENT  warning_contains_dependencies 

-  0  (#PCDATA)*> 

<  [ELEMENT  impleinentation_assuinptions_none 

-  0  <t!PCDATA)*> 

<  [  ELEMENT  warning_contains_ir. ::  leinentation_assiimptions 

-  0  (#PCDATA)*> 

<[ ELEMENT  description  -  -  (#PCDATA)»> 

< [ ELEMENT  requirements_satisf ied 

-  (#PCDATA)*> 

<[ ELEMENT  exceptions_raised 

-  (#PCDATA)»> 

< [ELEMENT  warning_unit_contains_iinplementation_dependencies 

-  -  (pragma_usage,  representation_clause_usage, 

hardware_dependencies ,  coinpiler_dependencies ) > 

<  [ELEME3'IT  warning_unit_contains_impleinentation_assumptions 

-  -  (use_assuinptions,  perfonnance_assuinptions )  > 

<[ ELEMENT  part_number  -  0  (# PCDATA )> 

<[ ELEMENT  author  -  0  PCDATA )> 

<[ ELEMENT  phone  -  0  (# PCDATA )> 

<[ ELEMENT  ddn  -  0  (# PCDATA )> 

<[ ELEMENT  version  -  0  (#PCDATA)> 

< [ELEMENT  change_suimnary_initial_release 

-  0  (#PCDATA)*> 
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<! ELEMENT  date  -  0  (#PCDATA)> 

< 'ELEMENT  documents_associated_with_revision 

-  0  (#PCDATA)> 

<  !  ELEMENT  change_smninary 

-  0  (#PCDATA)> 

<! ELEMENT  release_date 

-  0  (#PCDATA)> 

<! ELEMENT  distribution_and_copyright 

-  0  (#PCDATA)> 

<! ELEMENT  disclaimer  -  -  CDATA> 

< ! ELEMENT  pragma_usage 

-  0  (#PCDATA)*> 

<! ELEMENT  representation_clause_usage 

-  0  (#PCDATA)»> 

< ! ELEMENT  hardware_dependencies 

-  0  (#PCDATA)»> 

<  !  ELEI'IENT  compiler_dependencies 

-  0  (#PCDATA)*> 


<!  ELEMENT  use_assuinptions 

-  0  (#PCDATA)»> 


< ! ELEMENT  perf ormance_assumptions 

-  0  (#PCDATA)*> 


]> 


3.3.7  Prologue  Creation  and  Validation  Tools 

Interactive  support  for  prologue  creation  ranges  from  incorporating  an  example  and 
filling  in  the  blanks  with  your  preferred  editor  to  context  sensitive  editors  that  only 
allow  correct  prologues  to  be  created.  CDRL  360,  which  describes  SGML  capabilities 
on  the  repository,  discusses  this  range  of  editors  more  fully. 

Non-interactive  support  for  prologue  creation  includes  tools  that  add  a  skeleton 
prologue  to  a  compilation  unit  that  doesn't  have  one  and  that  analyze  the  unit's  code 
for  key  constructs  such  as  exceptions  and  pragmas,  putting  that  information  into  the 
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proper  area  of  the  prologue.  Boeing’s  O  Task  10  is  specifying  such  a  tool.  It  will  aid 
the  reuse  of  public  domain  source  such  as  SIMTEL20,  where  prologues  are  either 
missing  or  incomplete. 

Experiments  with  prologue  validation  were  conducted  using  the  current  version  of  the 
STARS  SGML  parser.  Firstly,  the  STARS  parser  does  not  completely  implement  the 
SGML  standard,  with  the  result  that  the  prologue  it  can  validate  is  not  identical  to  the 
standard  prologue.  The  examples  below  show  the  differences: 

1.  Markup  tags  used  in  Ada  source  code  must  start  w'ith  " — ''  so  that  they  will  be 
treated  as  comments  by  the  Ada  compiler.  The  choice  of  delimiter  characters  is 
permitted  through  the  use  of  an  SGML  declaration,  but  the  STARS  parser  does 
not  allow  this  declaration  to  be  specified.  Therefore,  delimiters  can  only  be 
altered  by  modifying  the  parser  source  code. 

2.  The  optional  markup  minimization  feature  SHORTTAG  is  not  implemented. 
SHORTTAG  allows  the  tag  close  delimiter  to  be  omitted  from  tags  that  are 
immediately  followed  by  another  tag.  For  example,  the  following  excerpt  from 
Design  Header 

—  1 Exceptions_Raised> 

—  I  None . 

—  1 1 Exceptions_Raised> 


—  I Implementation_Dependencies_NONE> 

—  I  Impleinentation_Assuinptions_NONE> 

—  I Distribution_and_Copyright> 

—  I  This  prologue  must  be  included  in  all  copies  of  this  software. 

can  be  abbreviated  to 


—  I Exceptions_Raised> 

—  I  None . 

—  I  I Exceptions_Raised 

—  I Implementation_Dependencies_NONE 

—  I Implementation_Assumptions_NONE 

—  I Distribution_and_Copyright> 

—  I  This  prologue  must  be  included  in  all  copies  of  this  software. 

SHORTFAG  also  allows  empty  tags.  For  example.  Simple  Subprogram 
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Header 

—  I  Description) 

—  I  An  example  of  an  empty  tag. 

—  I  1  Description) 

—  I Exceptions_Raised) 

—  1  None. 

—  I  I Exceptions_Raised) 
can  be  abbreviated  to 

—  I  Description) 

—  I  An  example  of  an  empty  tag. 

--Il> 


—  I Exceptions_Raised) 

—  I  None . 

-II  > 


3.  The  optional  markup  minimization  feature  SHORTREF  is  not  implemented. 
With  this  feature,  tags  can  be  replaced  by  a  single  character  or  short  strings. 
For  example,  the  end  tag 


—  I  I Warning_Unit_Contains_Implementation_Dependencies) 
can  be  replaced  by 


Secondly,  the  STARS  SGML  parser  is  too  slow  for  actual  repository  use:  a 
tw'enty-one  line  Ada  program  takes  about  four  minutes  to  parse.  Thirdly,  the  STARS 
SGML  parser  does  not  use  the  SGML  DTD  but  a  special  form  of  Backus-Naur 
notation.  This  is  related  to  its  less  than  full  support  of  SGML,  with  the  consequence 
that  maintaining  a  correct  DTD  is  not  sufficient  to  maintaining  the  prologue  validation 
software. 

We  recommend  that  any  SGML  parser  used  by  the  repository  to  validate  incoming 
compilation  units  implement  the  SGML  standard  completely. 
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4.  Guidelines  and  Standards  for  Technical  Documentation 

The  DoD  Computer-Aided  Acquisition  and  Logistic  Support  system  (CALS) 
initiative  aims  to  integrate  the  technical  manuals,  engineering  specifications,  etc.  of  the 
DoD  and  its  suppliers  into  a  homogeneous  electronic  system  to  provide  for  the 
"transition  from  current  paper-intensive  weapon  support  processes  to  the  efficient  use 
of  digital  information  technology".  To  that  end,  it  has  created  a  standard  for 
representing  such  information.  That  standard  is  the  Automated  Interchange  of 
Technical  Information  -  MIL-STD-1840A. 

The  "homogeneous  electronic"  philosophy  of  CALS  is  in  tune  with  that  of  the  STARS 
program  and  it  makes  a  lot  of  sense  for  STARS  to  operate  within  the  CALS 
framework.  CALS  is  open  in  that  it  allows  "foreign"  things  to  fit  within  its  framework 
and  if  they  prove  useful,  they  can  become  part  of  the  CALS  standard. 

At  tliis  point,  it  looks  like  some  parts  of  CALS,  such  as  IGES  and  CCITT  Group  4 
for  vector  and  raster  graphics  respectively,  should  be  utilized  directly  by  STARS. 
Other  parts,  such  as  document  format,  need  to  be  tailored  to  better  fit  STARS  needs. 
If  such  tailorings  prove  to  have  long-term,  wide-spread  value,  they  would  be 
incorporated  within  the  CALS  standard. 

4.1  Guidelines  for  Text 

There  seems  to  be  a  great  deal  of  confusion  about  CALS  and  SGML.  Many  people 
use  the  tw’O  terms  interchangeably  -  they  are  not.  Part  of  the  textual  specification  of 
CALS  uses  a  subset  of  the  SG.ML  specification.  SGML  (ISO  8879)  contains 
definitions  and  methods  for  marking  "textual"  material.  The  word  textual  has  placed  in 
quotes  because  SGML  has  been  used  for  such  things  as  musical  scores,  not  obviously 
textual  material.  In  Ada  terminology,  SGML  would  correspond  to  a  "generic"  and 
CALS  would  be  a  particular  "instantiation"  of  that  generic  capability. 

Preparation  of  the  textual  portion  of  a  technical  publication  in  an  automated  support 
environment  can  be  viewed  as  a  five  step  process: 

a.  creating  a  document  type  definition  (DTD)  for  publication  control; 

b.  authoring  the  publication  and  inserting  SGML  markup  tags; 

c.  verifying  that  the  syntax  is  correct  according  to  the  rules  of  SGML; 

d.  using  the  output  specification  to  compose  the  document  so  that  the  produced 
(printed  or  displayed)  copy  corresponds  to  the  proper  format  and  style;  and 

e.  generating  a  text  presentation  metafile  in  a  page  description  language  (PDL)  to 
drive  the  display  device,  such  as  a  printer  or  typesetter. 

Current  national  and  international  non-government  standards  do  not  adequately 
address  all  five  steps  of  the  publication  preparation  process.  ISO  8879  (SGML) 
addresses  steps  a,  b,  and  c.  No  approved  national  or  international  standards  exist  to 
support  steps  d  and  e. 
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MIL-STD-1840A  refers  to  MIL-M-2800i  for  handling  textual  information. 
MIL-M-28001  states  that  textual  information  shall  be  tagged  per  ISO  8879  and  that 
there  shall  be  Document  Type  Definitions  (DTDs)  and  Output  Specifications  to  define 
the  tags  and  how  to  handle  them.  ISO  8879  is  used  to  define  the  rules  for  the  DTDs. 
MIL-M-28001  defines  specific  DTDs  for  M1L-M-38784B  style  documents.  This 
style  of  document  is  used  by  the  Air  Force  for  some  of  its  Techmcal  Manuals  e.g.  a 
maintenance  manual  for  a  radio.  Where  MIL-M-38784B  is  not  applicable,  an 
alternative  DTD  must  be  prepared.  Tagging  and  parsing  are  well  defined.  Various 
standards  organizations  around  the  world  are  working  on  developing  Output 
Specification  standards.  Page  Description  Languages,  such  as  Postscript,  are  in 
common  use. 

4.1.1  SGML  Tag  Sets  and  DTDs 

There  are  two  areas  where  the  STARS  program  needs  to  do  further  work.  The  first  is 
in  the  area  of  building  a  SGML  tag  set,  witli  corresponding  Output  Specification, 
together  with  a  set  of  Document  Type  Definitions  (DTDs)  for  documents  useful  to 
people  using  STARS  technology.  Some  of  the  tags  defined  for  MIL-M-38784B  could 
be  used  but  several  new  ones  are  needed.  The  DTDs  required  are  very  different.  Part 
of  the  STARS  program  direction  is  reuse.  This  implies  not  only  reuse  of  code,  but 
reuse  of  design,  specifications,  test,  etc.  SGML  tags  should  be  defined  to  ensure  that 
information  in  a  document  can  be  properly  entered  and  indexed  in  a  database  for  later 
reuse. 

As  part  of  this  task,  a  small  DTD  was  developed  for  Technical  Reports  delivered 
during  this  period.  It  needs  to  be  enhanced  substantially  to  really  implement  the  intent 
of  SGML.  It  is  reproduced  here; 


< ! DOCTYPE  doc  [ 

<! ENTITY  %  text  '(  #PCDATA  )"  > 


<  !  ELEI'IENT 

doc 

- 

( 

front?  , 

body  ,  rear?  )  > 

< ! ELEMENT 

front 

- 

(  idinfo 

/ 

abstract?  ,  preface?  ,  contents  , 

tablist?  ) 

> 

<  !  ELEME’IT 

idinfo  - 

- 

pubno  , 

titleblk  ,  addresee*  ,  (mfr, contrno 

,  (  sigblk*  1  sigpage 

) 

) 

> 

< ! ELEMENT 

pubno  - 

- 

( 

PCDATA 

) 

> 

< ! ELEMENT 

titleblk  - 

- 

( 

doctype? 

/ 

prtitle  ,  stitle?  )  > 

< ! ELEMENT 

doctype 

- 

( 

ff  PCDATA 

) 

> 

<  !  ELEI'LENT 

prtitle 

- 

( 

#  PCDATA 

) 

> 

<  !  ELET^ENT 

stitle 

- 

( 

*  PCDATA 

) 

> 

< 1  ELEMENT 

addresee 

- 

( 

PCDATA 

) 

<  !  ELEM’^rr 

mf  r 

- 

( 

# PCDATA 

) 

> 

< ! ELEME  MT 

contrno 

- 

( 

# PCDATA 

) 

> 

<  !  ELEMEirX 

pubdate 

- 

( 

PCDATA 

) 

> 

<! ELEMENT 

sigblk 

o 

(  (  purpose 

?  ,  signer  ,  position  ,  organic? 

iluslist?  , 
»  ,  pubdate 


address?  , 
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date?  )  1 

%text  ) 

> 

<! ELEMENT 

purpose 

- 

o 

(  # PCDATA 

)  > 

< (ELEMENT 

signer 

- 

o 

(  # PCDATA 

)  > 

< ! ELEMENT 

position 

- 

o 

(  # PCDATA 

)  > 

< (ELEMENT 

organiz 

- 

o 

(  # PCDATA 

)  > 

< (ELEMENT 

address 

- 

o 

(  # PCDATA 

)  > 

< (ELEMENT 

date 

- 

o 

(  # PCDATA 

)  > 

< ( ELEMENT 

sigpage 

- 

o 

EMPTY  > 

< ( ELEMENT 

abstract 

- 

- 

(  para+  , 

keywords  )  > 

< ( ELEMENT 

keywords 

- 

- 

(  keyv/ord* 

)  > 

< (ELEMENT 

keyword 

- 

- 

(  # PCDATA 

)  > 

< ( ELEMENT 

preface 

- 

- 

(  para+  ) 

> 

< ( ELEMENT 

contents 

- 

o 

EMPTY  > 

< ( ELEMENT 

iluslist 

- 

o 

EMPTY  > 

< ( ELEMENT 

tablist 

- 

o 

emp: 1  > 

< ( ELEMENT 

body 

- 

- 

(  para0+  ) 

> 

< ( ELEMENT 

paraO 

- 

- 

(  title  , 

para*  ,  subpara*  )  > 

< ( ELEMENT 

subpara 

- 

- 

(  title  , 

paratext?  ,  para*  ,  subpara*  ) 

< ( ELEMENT 

title 

- 

- 

(  %text;  ) 

> 

< (ELEMENT 

para 

- 

- 

(  paratext 

)  > 

< ( ELEMENT 

paratext 

o 

o 

(  %text,'  i 

list  1  figure  |  table  ) *  > 

< ( ELEMENT 

list 

- 

- 

(  deflist 

)  > 

< ( ELEMENT 

deflist 

- 

- 

(  term  ]  def  ) *  > 

< ( ELEMENT 

term 

- 

- 

(  # PCDATA 

)*  > 

< (ELEMENT 

def 

- 

- 

(  %text;  1 

paratext  |  table  ) *  > 

<( ELEMENT 

figure 

- 

- 

(  graphic 

,  title  )  > 

< (ELEMENT 

table 

- 

- 

(  title  , 

graphic  )  > 

< (ELEMENT 

graphic 

- 

o 

EMPTY  > 

< ( ELEMENT 

rear 

- 

- 

(  appendix?  ,  glossary?  ,  index?  ,  lep?  , 

< (ELEMENT 

appendix 

- 

- 

(  title  1 

para0+  )*  > 

< (ELEMENT 

glossary 

- 

- 

(  glosshd 

1  deflist  )*  > 

< ( ELEMENT 

glosshd 

- 

- 

(  ((PCDATA 

)  > 

< ( ELEMENT 

index 

- 

o 

EMPTY  > 

< (ELEMENT 

lep 

- 

o 

EMPTY  > 

< ( ELEMENT 

chgrec 

- 

o 

EMPTY  > 

]> 

4.1.2  SGML  Tools 


The  second  area  is  tools  to  support  SGML  usage.  The  tools  will  be  separated  into 
three  types  for  discussion: 

a.  Parsers,  Validators,  etc.  -  tools  that  read  and  understand  SGML  tagged  data 

b.  Automatic  taggers  -  tools  that  automatically  insert  SGML  tags  into  a  file 

c.  Text  Editors  -  tools  that  interactively  aid  in  inserting  SGML  tags 
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4. 1.2.1  SGML  Parsers,  Validators,  etc. 

A  survey  was  conducted  to  determine  what  Parsers,  Validators,  etc.  were  available. 

Sobemap  of  Belgium  has  a  product  called  Markit.  It  was  the  first  on  the  market  and 
at  the  moment,  appears  to  have  the  most  capability.  It  can  run  as  a  standalone 
program  for  validation  and/or  to  extract  SGML  information.  It  can  also  be  used  as  a 
library  of  utilities  in  a  user  built  program  to  do  specialized  processing.  It  does  not 
have  a  good  reputation  but  that  appears  to  be  as  a  result  of  its  poor  handling  of  errors. 
Typically,  it  does  not  find  all  the  errors,  the  error  messages  are  not  helpful  in  defining 
what  is  wrong,  and  they  refer  to  line  numbers  which  are  not  helpful  in  determining  the 
location  of  the  error  since  lines  in  an  SGML  file  don't  correlate  to  lines  in  a  document 
that  produced  it.  The  product  is  written  in  C  and  runs  on  MS-DOS  and  UNIX 
systems.  Price  is  very  dependent  upon  capability  required  and  number  of  users. 
10-25  thousand  dollars  might  be  typical  for  a  modest  sized  group  of  users. 

Softvi’are  Exoterica  of  Canada  is  in  the  SGML  business  exclusively.  It  is  a  fairly  new 
product  but  already  has  quite  a  reputation.  They  have  capitalized  on  Sobemap's  error 
handling  problems  by  making  error  handling  one  of  their  strong  points.  It  does  not 
appear  to  be  quite  as  complete  as  the  Sobemap  product.  It  can  run  as  a  standalone 
program  for  validation  but  the  standalone  cannot  be  used  to  extract  SGML 
information.  It  can  also  be  used  as  a  library  of  utilities  in  a  user  built  program  to  do 
specialized  processing.  The  product  is  written  in  C  and  runs  on  VAX-VMS,  UNIX 
and  Macintosh  systems.  Price  is  very  dependent  upon  capability  required  and  number 
of  users.  8-20  thousand  dollars  might  be  typical  for  a  modest  sized  group  of  users. 

Datalogics  of  Chicago  is  entering  the  market.  Their  product  is  still  in  Beta  test.  It 
falls  far  short  of  fully  supporting  the  ISO  standard.  It  appears  to  be  an  entry  level 
product  to  support  CALS  with  their  other  documentation  tools.  It  can  run  as  a 
standalone  program  for  validation  but  the  standalone  cannot  be  used  to  extract  SGML 
information.  It  can  also  be  used  as  a  library  of  utilities  in  a  user  built  program  to  do 
specialized  processing.  The  product  is  written  in  C  and  runs  on  MS-DOS  and 
VAX-VMS  systems.  Pricing  is  unknown. 

IBM  in  Boulder  has  a  new  product  but  it  is  only  available  on  IBM  machines  under  the 
VM  system  and  there  do  not  appear  to  be  any  plans  to  expand  its  availability. 

There  is  also  an  SGML  "parser"  developed  under  a  STARS  Foundations  effort.  This 
SGML  processor  validates  that  the  input  file  conforms  to  the  DTD  for  a  specific 
document  type.  The  document  type  is  declared  within  the  file.  The  SGML  processor 
is  a  general-purpose  parser,  so  it  can  not  read  an  SGML  DTD  directly.  The  DTD  is 
translated  into  a  particular  form  of  Backus-Naur  notation,  called  BNF*.  Tlie 
processor  uses  the  BNF*  file  to  check  the  SGML  tagged  file  for  compliance.  Its 
major  difficulties  are  poor  performance,  poor  error  handling,  not  working  directly  with 
DTDs,  and  not  fully  supporting  SGML. 
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4. 1.2. 2  Automatic  SGML  Taggers 

In  the  area  of  aulomalic  tagging,  there  appears  to  only  be  one  contender  -  Avalanche 
Development  Company  of  Boulder  Colorado.  Their  IMSYS  product  tags  an  ASCII 
file  that  is  formatted  as  a  printed  page.  It  only  supports  CALS  documents.  They  are 
coming  out  with  a  new  product  called  FASTTAG  which  will  tag  any  style  document  in 
any  form.  They  will  supply  the  control  data  for  it  for  CALS  documents  and  this 
product  will  replace  their  IMS^’S  product.  For  non-CALS  documents,  you  have  to 
supply  the  control  data. 

4. 1.2. 3  SGML  Text  Editors 

SGML  editors  are  forthcoming  from  several  companies.  Context,  Interleaf,  Xyx’ision 
and  most  other  large  text  editing  companies  with  a  DoD  oriented  clientele  are  adding 
SGML  editing  capabilities  to  their  products.  Both  Sobemap  and  Software  Exoterica 
have  editors  specifically  tailored  to  SGML  editing.  In  addition,  there  is  an  SGML 
editor  developed  under  a  STARS  Foundation  effort.  It's  tagging  support  works  by 
expanding  specific  tags.  It  is  not  context  sensitive,  however.  This  means  that  any  tag 
can  be  hand-created  in  any  document  section  and  that  deletion  of  a  opening  or  closing 
tag  does  not  delete  its  partner  or  associated  text. 

The  best  approach  would  be  to  develop  or  obtain  an  SGML  editing  capability  that  was 
truly  context  sensitive  so  that  syntactical  tagging  errors  would  be  prevented.  The 
transition  to  SGML  tagging  is  more  difficult  than  learning  a  new'  document  formatting 
system  since  you  can  create  tagging  errors  by  misplacing  or  forgetting  constructs  just  as 
you  experience  compilation  errors  in  writing  Ada  code.  In  one  sense,  the  problem  is 
even  larger  than  learning  one  programming  language  since  many  different  DTDs  w'ill 
exist.  Context  sensitive  editors  exist  for  programming  languages.  The  only  difficultv 
here  is  to  create  a  editor  that  used  a  given  DTD  to  define  its  menus  and  rules  for 
allowable  constructs. 

The  Context  DOC  tool  also  demonstrates  a  long  term  direction  SGML  editing  should 
go  -  that  is,  towards  a  WYSIWYG  editor.  This  type  of  editor  requires  a  workstation 
w’ith  a  reasonable  bit-mapped  display.  While  it  may  be  true  that  dumb  terminals  still 
represent  the  majority  of  video  output  devices  available,  the  cost  of  workstations  is 
declining  in  step  with  the  rapid  hardware  advances. 

4.2  Guidelines  for  Graphics 

The  CCITT  Group  4  standard  for  ra.ster  graphics  is  a  CALS  standard  that  is  fairly 
w'idely  used  as  is  IGES  for  vector  graphics.  Graphics  delivered  to  the  repository 
should  be  in  one  of  these  tw'o  formats.  It  should  be  noted  that  in  both  of  these  cases, 
the  data  describes  the  graphic  and  not  the  knowledge  underlying  the  graphic.  For 
example,  while  IGES  data  may  contain  information  that  a  curved  line  is  actually  a 
circle,  it  does  not  contain  any  information  that  the  circle  represents  a  process  in  a  data 
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flow  diagram.  Transfer  if  this  information  will  require  further  investigation  and 
development. 
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